<html>
<!-- $LastChangedDate: 2010-02-03 19:48:51 -0500 (Wed, 03 Feb 2010) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Coding</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Coding</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Coding Style'>Coding Style</a></li>
  <li><a href='#Lua Coding Style'>Lua Coding Style</a></li>
  <li><a href='#Globals vs. Singletons'>Globals vs. Singletons</a></li>
  <li><a href='#Reminders'>Reminders</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview of Coding</h2>
<p><!--date-->[2007/12]</p>
<p>
</p>
<p>
Source code is written in C++.
For portability, the code is written to abstract
the graphics system and scene graph.
Generalized C++ classes and Facade classes are used.
For example, the Graph class is a Facade over an osg::Switch node.
</p>
<p>
The source code is designed to be modular and layered.
Layers (in the form of Facade and Mediator C++ classes)
keep the top-level of the program from becoming too dependent
on drivers, graphics API, scene graph library, etc.
</p>
<p>
To catch memory corruption or uninitialized data,
critical classes have a "type signature" data member
which is checked in DEBUG builds.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Coding Style'></a>
<h2>Coding Style</h2>
<p><!--date-->[2004,2008/04]</p>

<p>
Naming convention:
<ul>

<li>Camel-back letters.
</li>

<li>Functions/methods begin with capital letter.
</li>

<li>Class members prefixed with "m" (or "ms" if static).
<br>Don't bother writing "mp"/"mr" for pointers/references (too pedantic, compiler will catch misuse).
</li>

<li>Static vars prefixed with "s", static members with "ms"
<br>whether static members begin with "s" depends on whether the fact it's shared should be exposed or concealed
</li>

<li><code>typedef TYPE value_type;</code> declared by wrapper classes over fundamental types (OSG convention).
</li>

<li>Place limited-use or perilous code in "RESTRICT" sub-namespace (not "restricted" which C99 reserves).
</li>

<li><a href='#Singletons'>Singletons</a>:
<br>Create a macro named GET_CLASS() for singletons (or globals that can behave as singletons).
</li>

<li><a href='#Globals'>Globals</a>:
  <ul>
    <li>Put widely-accessible globals in "global" namespace or put "global" in their name.
    </li>
<pre>
// Alternative using a single global:
namespace module {
namespace global {

World gWorld;

} // namespace global
} // namespace module
</pre>

<pre>
// Alternative using a struct of globals:
namespace module {
struct Globals
{
    Window mWindow;
    Gui    mGui;
};      
Globals gGlobals;
} // namespace module
</pre>
    <li>Put restricted-use or limited-scope globals in "RESTRICT" namespace
        ("restricted" is a C99 reserved word).
    </li>
  </ul>

<li>"s" suffix for a plurality such as container
<br>Searchability is more important than spelling.
<br>Eg, write "factorys" [sic] not "factories".
</li>

<li>Get(), Set() methods for interface to private members or to abtract data,
<br>Get() should return a const whenever possible
</li>

<li>Never write "static" to maintain threaded-code (see <a href='#Threads'>Threads</a>).
</li>

</ul>
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Lua Coding Style'></a>
<h2>Lua Coding Style</h2>
<p><!--date-->[2008/06]</p>
<p>
See <a href='../../scripts/module.txt'>scripts/module.txt</a>.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Globals vs. Singletons'></a>
<a name='Globals'></a>
<a name='Singletons'></a>
<h2>Globals vs. Singletons</h2>
<p><!--date-->[2009/10]</p>
<p>
Singletons are preferred (despite being slightly slower and cumbersome to write).
A limited amount of globals are used for very-frequently-accessed globals
or some singletons themselves need to access a global that is plain data.
</p>

<h3>General Information about Globals and Singletons</h3>
<p>
Singletons have two problems:
<ol>
  <li>They won't be automatically destroyed at program exit.</li>
  <li>Overuse of singletons can lead to two singletons with a circular dependence.</li>
</ol>
</p>
<p>
When multiple globals are really necessary and one global depends on another,
an option is a global C++ struct.
C++ defines the order of construction of members in the order they are declared
(don't confuse with the order of initialization list).
C++ will automatically destroy them in the reverse order at program exit.
<pre>
#define GET_WINDOW() (module::gGlobals.mWindow)  // behaves as a singleton so named accordingly
#define GET_GUI()    (module::gGlobals.mGui)

namespace module {

struct Globals
{
    Window    mWindow;    // no dependencies
    Gui       mGui;       // depends on mWindow (ok)
};

#if PROGRAM_MODULE_CC
Globals globals;
#else
extern Globals globals;
#endif

} // namespace module
</pre>
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Reminders'></a>
<h2>Reminders</h2>
<p><!--date-->[2004,2009/05]</p>

<h3>Do</h3>

<ul>

<li>Prefer C++ &lt;cmath&gt; over C &lt;math.h&gt; and write the <code>std::</code> prefix.</li>
<p>
C++ math functions are overloaded to the appropriate type.
Eg, sin(f) needlessly promotes to a double,
but std::sin(f) is automatically chooses the equivalent of C sinf(f).
</p>

<li>global vs. globals:</li>
<p>
namespace global (singular)<br>class Globals (plural)
</p>

<li>Protect and indicate ownership of pointers using SafePtr template class.</li>
<p>
SafePtr prevents deleting the pointed-to object.
<pre>
class Object
{
    Shape*         GetShape( void );
    SafePtr&lt;Shape&gt; GetShape( void );
};
</pre>

<li>
Avoid dangling pointers using SharedPtr template class.
</li>
<p>
Object A passes a pointer to its member to object B.
But A could be destroyed before B uses the pointer.
Or B could delete the passed object, then A tries to use it.
SharedPtr can prevent these problems.
</p>

<!-- obsolete in Palomino V2 -->
<!-- <li> -->
<!-- Occasionally compile with DEBUG=2. -->
<!-- </li> -->

<li>
Do write world coordinate constants inside the WORLD_COORD() macro
in case world coordinates might scaled in the future.
</li>

<li>
(Assuming NULL cannot be avoided) do NULLify a pointer to a deleted object.
This protects against multiple deletions in case a member pointer is static
(delete NULL is a NOP).
</li>

<li>
A bug results if a loop that iterates a list
calls a function that alters it.
<!-- Dlist was deprecated -->
<!-- Dlist class can tolerate removing one link during iteration (not recommended). -->
</li>

</ul>

<h3>Don't</h3>

<ul>

<li>
Don't save state across multiple frames (in an Object) unless the state is per-view
(since multiple views are possible).
</li>

</ul>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Wed Feb  3 18:24:24 CST 2010
<!-- hhmts end -->
</font>
</p>

</body>
</html>
